In This Topic

Introduction

This article describes the aspects and parts of the Rapid Toolkit for Sparkplug data model that are used when developing providers (Sparkplug edge nodes and devices).

Sparkplug Edge Node Object

Sparkplug edge node is a component in Sparkplug system that communicates with the broker using the Sparkplug protocol and topic namespace, and acts as a gateway to its underlying system (such as PLC, sensors, internal process variables, etc.). In Rapid Toolkit for Sparkplug, a Sparkplug edge node is represented by an instance of the EasySparkplugEdgeNode Class.

Your code create an instance of the EasySparkplugEdgeNode Class, and uses its properties and methods to define the edge node parameters, contents, and behavior.

You will typically create and start just one instance of the EasySparkplugEdgeNode Class in your program. There is nothing, however, that prevents you from exposing multiple Sparkplug edge nodes from the same program, by using multiple EasySparkplugEdgeNode Class instances.

Edge Node Object Configuration Properties

The EasySparkplugEdgeNode Class has various properties that can be used to influence how the edge node works. The most important ones are explained below.

The Sparkplug system descriptor is stored in the SystemDescriptor Property (in the simplest case, the role of the system descriptor is to provide the address of the MQTT broker.).
The Sparkplug edge node ID is stored in the EdgeNodeId Property.
The Sparkplug group ID is stored in the GroupId Property.
The collection of Sparkplug metrics that this edge node publishes is contained in the Metrics Property of the edge node. You can add or remove your metrics in this collection. Note that these are the metrics that are defined on the edge node itself; additional metrics may exist on the devices that the edge node contains.
The collection of Sparkplug devices in edge node is contained in the Devices Property of the edge node. You can add or remove your devices in this collection. Note that the presence of one or more devices in the Sparkplug edge node is optional. The edge node may have no devices, and only expose metric on the edge node itself.
The host ID of the primary host application the edge node is associated with is stored in the PrimaryHostId Property (note that specifying non-empty primary host ID significantly changes the behavior of the Sparkplug edge node - with non-empty primary host ID specified, the edge node does not publish any data unless it can positively determine that the primary host application is online.).

Some edge node object properties can be pre-set using the object constructor (see below). However, you can always create the edge node object empty (using the default constructor), and then set its properties by assigning to them.

Constructing the Edge Node Object

An instance of the EasySparkplugEdgeNode Class is normally created by calling its constructor. The default constructor (with no parameters) creates the edge node object with all defaults. There are various constructor overloads that allow you to initialize the newly created edge node object with certain most important properties (such as the MQTT broker URL, and the Sparkplug group ID and edge node ID) upfront. The various ways of constructing the edge node object are illustrated in the example below, and in the examples listed in the "See Also" section at the bottom of the page..

A common way of constructing the EasySparkplugEdgeNode Class instance is to use the constructor that takes the URL of the MQTT broker endpoint, and the Sparkplug group ID and edge node ID as arguments (this is illustrated in the example code further below).

// This example shows different ways of constructing the EasySparkplugEdgeNode object.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.EasySparkplug;

namespace SparkplugDocExamples.EdgeNode._EasySparkplugEdgeNode
{
    class Construction
    {
        static public void Main1()
        {
            // The toolkit provides a ready-made shared instance of the edge node object which you can use without even
            // having to construct it. Not recommended for use in library code, because it is a shared instance, and its
            // usage may therefore conflict with other code using the same instance.
            var edgeNode0 = EasySparkplugEdgeNode.SharedInstance;

            
            // The simplest way to construct the edge node object is to use the default constructor. The edge node will
            // connect to the default broker URL "mqtt://localhost". Group ID is "easyGroup", edge node ID and primary host
            // ID will be auto-generated.
            var edgeNode1 = new EasySparkplugEdgeNode();


            // The edge node object can be constructed with a specific broker URL string passed as an argument to the
            // constructor. This relies on the implicit conversion from string to SparkplugBrokerDescriptor.
            var edgeNode2 = new EasySparkplugEdgeNode("mqtt://localhost:1883");


            // The broker URL can also be specified using the Uri object.
            var edgeNode3 = new EasySparkplugEdgeNode(new Uri("mqtt://localhost:1883"));


            // You can construct the edge node object with a specific broker descriptor, which allows you to set all its
            // parameters;
            var edgeNode4 = new EasySparkplugEdgeNode(
                new SparkplugBrokerDescriptor
                {
                    Host = "localhost",
                    Password = "password",
                    Port = 1883,
                    UserName = "admin",
                });


            // The sparkplug group ID and edge node ID can be specified as additional arguments to the constructor.
            var edgeNode5 = new EasySparkplugEdgeNode("mqtt://localhost:1883", "myGroup", "myEdgeNode");


            // The primary host ID of the application can also be specified, using a different constructor overload (when
            // not specified, i.e. left empty, the component will not use the primary host application logic).
            var edgeNode6 = new EasySparkplugEdgeNode("mqtt://localhost:1883", "myPrimaryHost", "myGroup", "myEdgeNode");


            // You do not have to specify everything in the constructor. The basic properties can be set later - but before
            // the edge node is started.
            var edgeNode7 = new EasySparkplugEdgeNode();
            edgeNode7.SystemDescriptor = new SparkplugSystemDescriptor("mqtt://localhost:1883");
            edgeNode7.GroupId = "myGroup";
            edgeNode7.EdgeNodeId = "myEdgeNode";


            // If the language supports property initializers (such as C# or VB.NET), the above code can be written more
            // concisely.
            var edgeNode8 = new EasySparkplugEdgeNode
            {
                GroupId = "myGroup",
                EdgeNodeId = "myEdgeNode",
                SystemDescriptor = new SparkplugSystemDescriptor("mqtt://localhost:1883"),
            };


            // For more advanced scenarios, a SparkplugSystemDescriptor can be passed to the constructor instead of the 
            // SparkplugBrokerDescriptor. In the example below, this allows you to specify the Sparkplug version.
            var edgeNode9 = new EasySparkplugEdgeNode(
                new SparkplugSystemDescriptor("mqtt://localhost:1883", SparkplugVersions.PayloadA), 
                "myPrimaryHost", 
                "myGroup", 
                "myEdgeNode");


            // If the language supports collection initializers (such as C# or VB.NET), the edge node object can be
            // constructed with its metrics (the contents of the Metrics collection), in a single statement.
            var edgeNode10 = new EasySparkplugEdgeNode("myPrimaryHost", "myGroup", "myEdgeNode")
            {
                new SparkplugMetric("Constant1").ConstantValue(42),
                new SparkplugMetric("Constant2").ConstantValue("abc")
            };
        }
    }
}

' This example shows different ways of constructing the EasySparkplugEdgeNode object.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasySparkplug

Namespace Global.SparkplugDocExamples.EdgeNode._EasySparkplugEdgeNode
    Class Construction
        Public Shared Sub Main1()
            ' The toolkit provides a ready-made shared instance of the edge node object which you can use without even
            ' having to construct it. Not recommended for use in library code, because it is a shared instance, and its
            ' usage may therefore conflict with other code using the same instance.
            Dim edgeNode0 = EasySparkplugEdgeNode.SharedInstance


            ' The simplest way to construct the edge node object is to use the default constructor. The edge node will
            ' connect to the default broker URL "mqtt://localhost". Group ID is "easyGroup", edge node ID and primary host
            ' ID will be auto-generated.
            Dim edgeNode1 = New EasySparkplugEdgeNode()


            ' The edge node object can be constructed with a specific broker URL string passed as an argument to the
            ' constructor. This relies on the implicit conversion from string to SparkplugBrokerDescriptor.
            Dim edgeNode2 = New EasySparkplugEdgeNode("mqtt://localhost:1883")


            ' The broker URL can also be specified using the Uri object.
            Dim edgeNode3 = New EasySparkplugEdgeNode(New Uri("mqtt://localhost:1883"))


            ' You can construct the edge node object with a specific broker descriptor, which allows you to set all its
            ' parameters;
            Dim edgeNode4 = New EasySparkplugEdgeNode(
                New SparkplugBrokerDescriptor With
                {
                    .Host = "localhost",
                    .Password = "password",
                    .Port = 1883,
                    .UserName = "admin"
                })


            ' The sparkplug group ID and edge node ID can be specified as additional arguments to the constructor.
            Dim edgeNode5 = New EasySparkplugEdgeNode("mqtt://localhost:1883", "myGroup", "myEdgeNode")


            ' The primary host ID of the application can also be specified, using a different constructor overload (when
            ' not specified, i.e. left empty, the component will not use the primary host application logic).
            Dim edgeNode6 = New EasySparkplugEdgeNode("mqtt://localhost:1883", "myPrimaryHost", "myGroup", "myEdgeNode")


            ' You do not have to specify everything in the constructor. The basic properties can be set later - but before
            ' the edge node is started.
            Dim edgeNode7 = New EasySparkplugEdgeNode()
            edgeNode7.SystemDescriptor = New SparkplugSystemDescriptor("mqtt://localhost:1883")
            edgeNode7.GroupId = "myGroup"
            edgeNode7.EdgeNodeId = "myEdgeNode"


            ' If the language supports property initializers (such as C# or VB.NET), the above code can be written more
            ' concisely.
            Dim edgeNode8 = New EasySparkplugEdgeNode With
            {
                .GroupId = "myGroup",
                .EdgeNodeId = "myEdgeNode",
                .SystemDescriptor = New SparkplugSystemDescriptor("mqtt://localhost:1883")
            }


            ' For more advanced scenarios, a SparkplugSystemDescriptor can be passed to the constructor instead of the 
            ' SparkplugBrokerDescriptor. In the example below, this allows you to specify the Sparkplug version.
            Dim edgeNode9 = New EasySparkplugEdgeNode(
                New SparkplugSystemDescriptor("mqtt://localhost:1883", SparkplugVersions.PayloadA),
                "myPrimaryHost",
                "myGroup",
                "myEdgeNode")


            ' If the language supports collection initializers (such as C# or VB.NET), the edge node object can be
            ' constructed with its metrics (the contents of the Metrics collection), in a single statement.
            Dim edgeNode10 = New EasySparkplugEdgeNode("myPrimaryHost", "myGroup", "myEdgeNode") From
            {
                New SparkplugMetric("Constant1").ConstantValue(42),
                New SparkplugMetric("Constant2").ConstantValue("abc")
            }
        End Sub
    End Class
End Namespace

Sparkplug Device

Sparkplug device (a device/sensor connected to the Sparkplug edge node) is represented by the SparkplugDevice Class in Rapid Toolkit for Sparkplug.

A Sparkplug device is typically a sensor, actuator, or other endpoint that communicates its data through a Sparkplug edge node. Devices do not connect directly to the MQTT broker; instead, they internally connect to an edge node, which aggregates and forwards their data using the Sparkplug protocol. The edge node manages the lifecycle, state, and data of its devices, ensuring reliable and structured communication with the broker.

Note that the presence of one or more devices in the Sparkplug edge node is optional. The edge node may have no devices, and only expose metric on the edge node itself.

The Sparkplug device ID is stored in the DeviceId Property. The collection of Sparkplug metrics that this device publishes is contained in the Metrics Property of the device. You can add or remove your metrics in this collection.

You can separately create the device object and then add it to the Devices collection of the edge node. Alternatively, you can use the static CreateIn Method, which combines creation of the device object, setting its device ID, and adding it into the parent edge node, in one method call.

Sparkplug Producers

Both the Sparkplug edge node object (EasySparkplugEdgeNode Class) and the Sparkplug device (SparkplugDevice Class) described above are Sparkplug producers, and share many common characteristics, some of which are described here.

Each Sparkplug producer (edge node or device) is associated with a data source. Data source is an abstract concept, and it can be practically anything that the edge or device communicates with. Rapid Toolkit for Sparkplug does not prescribe how the communication with the data source should be done. Handling the communication is the primary task of the code you need to write when using Rapid Toolkit for Sparkplug to create Sparkplug edge nodes. Rapid Toolkit for Sparkplug, however, defines an interface to the data source with regard to its connections and disconnections. This is because the Sparplug specification prescribes the proper behavior of Sparkplug edge nodes and devices related to the data source status.

Also, each Sparkplug producer can adjust its behavior to the state of its Sparkplug environment. The producer's data source can be connected whenever the edge node or device is started, but also depending on other factors - such as whether the Sparkplug system (MQTT broker) is successfully connected, or whether the primary host application (when configured) for the edge node is currently online. This is controlled by the DataSourceConnectionMode Property on the edge node or device.

provides periodic polling for the metrics on the edge node or device with an interval specified by the PublishingInterval Property. You can also choose to disable the polling and report any changed data from your code explicitly, by turning on the ReportByException Property.

Sparkplug Metric

The Sparkplug metric is a data point in the Sparkplug system, and is represented by the SparkplugMetric Class in Rapid Toolkit for Sparkplug. These also represent tags in classic SCADA systems. The metric contains data (value and timestamp) that is published to Sparkplug, and/or can be set from Sparkplug (by Sparkplug commands).

Each metric has a name (a string; Name Property). The name must be unique among the metrics in the parent (edge node, or a device).

If your implementation needs it, the metric can be associated with any object you like. This is done using the State Property of the metric.

You can separately create the metric object and then add it to the Metrics collection of the edge node or device. Alternatively, you can use the static CreateIn Method, which combines creation of the metric object, setting its name, and adding it into the parent edge node or device, in one method call.

After the initial creation of the metric, it is then common to configure it further, as described in Sparkplug Metric Configuration.

.NET

C#
VB.NET

// This example show to add metrics to the Sparkplug edge node and/or device using the CreateIn method. This method combines
// creation of the metric with adding it to the parent component.
//
// You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
// program, to subscribe to the edge node data. 
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.EasySparkplug;
using OpcLabs.EasySparkplug.OperationModel;

namespace SparkplugDocExamples.EdgeNode._SparkplugMetric
{
    class CreateIn
    {
        static public void Main1()
        {
            // Note that the default port for the "mqtt" scheme is 1883.
            var hostDescriptor = new SparkplugHostDescriptor("mqtt://localhost");

            // Instantiate the edge node object and hook events.
            var edgeNode = new EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo");
            edgeNode.SystemConnectionStateChanged += edgeNode_Main1_SystemConnectionStateChanged;

            // Create a constant metric in the edge node.
            SparkplugMetric constantMetric = SparkplugMetric.CreateIn(edgeNode, "Constant").ConstantValue("abc");

            // Create a device.
            SparkplugDevice device = SparkplugDevice.CreateIn(edgeNode, "Device");

            // Create a read/write metric ("register") in the device.
            SparkplugMetric readWriteMetric = SparkplugMetric.CreateIn(device, "ReadWrite").ReadWriteValue(0);

            // Note: You can, of course, also create the SparkplugMetric using its constructor, and add it to the Metrics
            // collection then on the edge node or device then. The CreateIn method is just a convenience shorthand for
            // this; in addition, it returns the created metric, so you can easily configure it further, and/or store it.

            // Start the edge node.
            Console.WriteLine("The edge node is starting...");
            edgeNode.Start();

            Console.WriteLine("The edge node is started.");
            Console.WriteLine();

            // Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...");
            Console.ReadLine();

            // Stop the edge node.
            Console.WriteLine("The edge node is stopping...");
            edgeNode.Stop();

            Console.WriteLine("The edge node is stopped.");
        }


        static void edgeNode_Main1_SystemConnectionStateChanged(
            object sender,
            SparkplugConnectionStateChangedEventArgs eventArgs)
        {
            // Display the new connection state (such as when the connection to the broker succeeds or fails).
            Console.WriteLine($"{nameof(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}");
        }
    }
}

' This example show to add metrics to the Sparkplug edge node and/or device using the CreateIn method. This method combines
' creation of the metric with adding it to the parent component.
'
' You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
' program, to subscribe to the edge node data.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasySparkplug
Imports OpcLabs.EasySparkplug.OperationModel

Namespace Global.SparkplugDocExamples.EdgeNode._SparkplugMetric
    Class CreateIn
        Public Shared Sub Main1()
            ' Note that the default port for the "mqtt" scheme is 1883.
            Dim hostDescriptor = New SparkplugHostDescriptor("mqtt://localhost")

            ' Instantiate the edge node object and hook events.
            Dim edgeNode = New EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo")
            AddHandler edgeNode.SystemConnectionStateChanged, AddressOf edgeNode_Main1_SystemConnectionStateChanged

            ' Create a constant metric in the edge node.
            Dim constantMetric As SparkplugMetric = SparkplugMetric.CreateIn(edgeNode, "Constant").ConstantValue("abc")

            ' Create a device.
            Dim device As SparkplugDevice = SparkplugDevice.CreateIn(edgeNode, "Device")

            ' Create a read/write metric ("register") in the device.
            Dim readWriteMetric As SparkplugMetric = SparkplugMetric.CreateIn(device, "ReadWrite").ReadWriteValue(0)

            ' Note: You can, of course, also create the SparkplugMetric using its constructor, and add it to the Metrics
            ' collection then on the edge node or device then. The CreateIn method is just a convenience shorthand for
            ' this; in addition, it returns the created metric, so you can easily configure it further, and/or store it.

            ' Start the edge node.
            Console.WriteLine("The edge node is starting...")
            edgeNode.Start()

            Console.WriteLine("The edge node is started.")
            Console.WriteLine()

            ' Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...")
            Console.ReadLine()

            ' Stop the edge node.
            Console.WriteLine("The edge node is stopping...")
            edgeNode.Stop()

            Console.WriteLine("The edge node is stopped.")
        End Sub

        Private Shared Sub edgeNode_Main1_SystemConnectionStateChanged _
            (ByVal sender As Object, ByVal eventArgs As SparkplugConnectionStateChangedEventArgs)
            ' Display the new connection state (such as when the connection to the broker succeeds or fails).
            Console.WriteLine($"{NameOf(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}")
        End Sub

    End Class
End Namespace

Interfaces and Extension Methods

Rapid Toolkit for Sparkplug uses interfaces where appropriate. This means that in many cases, when we refer to member of Rapid Toolkit for Sparkplug objects, these members are actually defined by some interface that the object implements. Specifically, for example:

The main members of the EasySparkplugEdgeNode Class are actually implementations of IEasySparkplugEdgeNode Interface members.
The main members of the SparkplugDevice Class are actually implementations of the ISparkplugDevice Interface members.
Some members of the SparkplugMetric Class come from the ISparkplugMetricEvents Interface.

Consequently, at many places, Rapid Toolkit for Sparkplug uses the interface types for method arguments and properties, instead of the concrete classes.

The classes and interfaces contain only methods that are necessary to express the required object functionality. The remaining methods (and method overloads) simply build on these "core" methods, and are implemented as extension methods on the interfaces or classes. In most languages (certainly in C# and VB.NET), this design leads to the same syntax as if all the methods were implemented directly on the "core" concrete object.

Sparkplug is a trademark of Eclipse Foundation, Inc. "MQTT" is a trademark of the OASIS Open standards consortium. Other related terms are trademarks of their respective owners. Any use of these terms on this site is for descriptive purposes only and does not imply any sponsorship, endorsement or affiliation.

Examples - Sparkplug Edge Node

Examples - Sparkplug Edge Node - Start and stop, connect and specify client ID

Examples - Sparkplug Edge Node - Start and stop, connect with authentication

Examples - Sparkplug Edge Node - Start and stop, connect with MQTT 5

Examples - Sparkplug Edge Node - Start and stop, connect with TLS

Examples - Sparkplug Edge Node - Start and stop, connect with WebSocket